home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / xcb / xcb.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  14.5 KB  |  451 lines
  1. /*
  2.  * Copyright (C) 2001-2006 Bart Massey, Jamey Sharp, and Josh Triplett.
  3.  * All Rights Reserved.
  4.  *
  5.  * Permission is hereby granted, free of charge, to any person obtaining a
  6.  * copy of this software and associated documentation files (the "Software"),
  7.  * to deal in the Software without restriction, including without limitation
  8.  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  9.  * and/or sell copies of the Software, and to permit persons to whom the
  10.  * Software is furnished to do so, subject to the following conditions:
  11.  *
  12.  * The above copyright notice and this permission notice shall be included in
  13.  * all copies or substantial portions of the Software.
  14.  *
  15.  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16.  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17.  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18.  * AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  19.  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  20.  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21.  *
  22.  * Except as contained in this notice, the names of the authors or their
  23.  * institutions shall not be used in advertising or otherwise to promote the
  24.  * sale, use or other dealings in this Software without prior written
  25.  * authorization from the authors.
  26.  */
  27.  
  28. #ifndef __XCB_H__
  29. #define __XCB_H__
  30. #include <sys/types.h>
  31.  
  32. #if defined(__solaris__)
  33. #include <inttypes.h>
  34. #else
  35. #include <stdint.h>
  36. #endif
  37.  
  38. #include <sys/uio.h>
  39. #include <pthread.h>
  40.  
  41.  
  42. #ifdef __cplusplus
  43. extern "C" {
  44. #endif
  45.  
  46. /**
  47.  * @file xcb.h
  48.  */
  49.  
  50. /**
  51.  * @defgroup XCB_Core_API XCB Core API
  52.  * @brief Core API of the XCB library.
  53.  *
  54.  * @{
  55.  */
  56.  
  57. /* Pre-defined constants */
  58.  
  59. /** Current protocol version */
  60. #define X_PROTOCOL 11
  61.  
  62. /** Current minor version */
  63. #define X_PROTOCOL_REVISION 0
  64.  
  65. /** X_TCP_PORT + display number = server port for TCP transport */
  66. #define X_TCP_PORT 6000
  67.  
  68. #define XCB_TYPE_PAD(T,I) (-(I) & (sizeof(T) > 4 ? 3 : sizeof(T) - 1))
  69.  
  70. /* Opaque structures */
  71.  
  72. /**
  73.  * @brief XCB Connection structure.
  74.  *
  75.  * A structure that contain all data that  XCB needs to communicate with an X server.
  76.  */
  77. typedef struct xcb_connection_t xcb_connection_t;  /**< Opaque structure containing all data that  XCB needs to communicate with an X server. */
  78.  
  79.  
  80. /* Other types */
  81.  
  82. /**
  83.  * @brief Generic iterator.
  84.  *
  85.  * A generic iterator structure.
  86.  */
  87. typedef struct {
  88.     void *data;   /**< Data of the current iterator */
  89.     int rem;    /**< remaining elements */
  90.     int index;  /**< index of the current iterator */
  91. } xcb_generic_iterator_t;
  92.  
  93. /**
  94.  * @brief Generic reply.
  95.  *
  96.  * A generic reply structure.
  97.  */
  98. typedef struct {
  99.     uint8_t   response_type;  /**< Type of the response */
  100.     uint8_t  pad0;           /**< Padding */
  101.     uint16_t sequence;       /**< Sequence number */
  102.     uint32_t length;         /**< Length of the response */
  103. } xcb_generic_reply_t;
  104.  
  105. /**
  106.  * @brief Generic event.
  107.  *
  108.  * A generic event structure.
  109.  */
  110. typedef struct {
  111.     uint8_t   response_type;  /**< Type of the response */
  112.     uint8_t  pad0;           /**< Padding */
  113.     uint16_t sequence;       /**< Sequence number */
  114.     uint32_t pad[7];         /**< Padding */
  115.     uint32_t full_sequence;  /**< full sequence */
  116. } xcb_generic_event_t;
  117.  
  118. /**
  119.  * @brief Generic error.
  120.  *
  121.  * A generic error structure.
  122.  */
  123. typedef struct {
  124.     uint8_t   response_type;  /**< Type of the response */
  125.     uint8_t   error_code;     /**< Error code */
  126.     uint16_t sequence;       /**< Sequence number */
  127.     uint32_t pad[7];         /**< Padding */
  128.     uint32_t full_sequence;  /**< full sequence */
  129. } xcb_generic_error_t;
  130.  
  131. /**
  132.  * @brief Generic cookie.
  133.  *
  134.  * A generic cookie structure.
  135.  */
  136. typedef struct {
  137.     unsigned int sequence;  /**< Sequence number */
  138. } xcb_void_cookie_t;
  139.  
  140.  
  141. /* Include the generated xproto header. */
  142. #include "xproto.h"
  143.  
  144.  
  145. /** XCB_NONE is the universal null resource or null atom parameter value for many core X requests */
  146. #define XCB_NONE 0L
  147.  
  148. /** XCB_COPY_FROM_PARENT can be used for many xcb_create_window parameters */
  149. #define XCB_COPY_FROM_PARENT 0L
  150.  
  151. /** XCB_CURRENT_TIME can be used in most requests that take an xcb_timestamp_t */
  152. #define XCB_CURRENT_TIME 0L
  153.  
  154. /** XCB_NO_SYMBOL fills in unused entries in xcb_keysym_t tables */
  155. #define XCB_NO_SYMBOL 0L
  156.  
  157.  
  158. /* xcb_auth.c */
  159.  
  160. /**
  161.  * @brief Container for authorization information.
  162.  *
  163.  * A container for authorization information to be sent to the X server.
  164.  */
  165. typedef struct xcb_auth_info_t {
  166.     int   namelen;  /**< Length of the string name (as returned by strlen). */
  167.     char *name;     /**< String containing the authentication protocol name, such as "MIT-MAGIC-COOKIE-1" or "XDM-AUTHORIZATION-1". */
  168.     int   datalen;  /**< Length of the data member. */
  169.     char *data;   /**< Data interpreted in a protocol-specific manner. */
  170. } xcb_auth_info_t;
  171.  
  172.  
  173. /* xcb_out.c */
  174.  
  175. /**
  176.  * @brief Forces any buffered output to be written to the server.
  177.  * @param c: The connection to the X server.
  178.  * @return > @c 0 on success, <= @c 0 otherwise.
  179.  *
  180.  * Forces any buffered output to be written to the server. Blocks
  181.  * until the write is complete.
  182.  */
  183. int xcb_flush(xcb_connection_t *c);
  184.  
  185. /**
  186.  * @brief Returns the maximum request length that this server accepts.
  187.  * @param c: The connection to the X server.
  188.  * @return The maximum request length field.
  189.  *
  190.  * In the absence of the BIG-REQUESTS extension, returns the
  191.  * maximum request length field from the connection setup data, which
  192.  * may be as much as 65535. If the server supports BIG-REQUESTS, then
  193.  * the maximum request length field from the reply to the
  194.  * BigRequestsEnable request will be returned instead.
  195.  *
  196.  * Note that this length is measured in four-byte units, making the
  197.  * theoretical maximum lengths roughly 256kB without BIG-REQUESTS and
  198.  * 16GB with.
  199.  */
  200. uint32_t xcb_get_maximum_request_length(xcb_connection_t *c);
  201.  
  202. /**
  203.  * @brief Prefetch the maximum request length without blocking.
  204.  * @param c: The connection to the X server.
  205.  *
  206.  * Without blocking, does as much work as possible toward computing
  207.  * the maximum request length accepted by the X server.
  208.  *
  209.  * Invoking this function may cause a call to xcb_big_requests_enable,
  210.  * but will not block waiting for the reply.
  211.  * xcb_get_maximum_request_length will return the prefetched data
  212.  * after possibly blocking while the reply is retrieved.
  213.  *
  214.  * Note that in order for this function to be fully non-blocking, the
  215.  * application must previously have called
  216.  * xcb_prefetch_extension_data(c, &xcb_big_requests_id) and the reply
  217.  * must have already arrived.
  218.  */
  219. void xcb_prefetch_maximum_request_length(xcb_connection_t *c);
  220.  
  221.  
  222. /* xcb_in.c */
  223.  
  224. /**
  225.  * @brief Returns the next event or error from the server.
  226.  * @param c: The connection to the X server.
  227.  * @return The next event from the server.
  228.  *
  229.  * Returns the next event or error from the server, or returns null in
  230.  * the event of an I/O error. Blocks until either an event or error
  231.  * arrive, or an I/O error occurs.
  232.  */
  233. xcb_generic_event_t *xcb_wait_for_event(xcb_connection_t *c);
  234.  
  235. /**
  236.  * @brief Returns the next event or error from the server.
  237.  * @param c: The connection to the X server.
  238.  * error status of the operation.
  239.  * @return The next event from the server.
  240.  *
  241.  * Returns the next event or error from the server, if one is
  242.  * available, or returns @c NULL otherwise. If no event is available, that
  243.  * might be because an I/O error like connection close occurred while
  244.  * attempting to read the next event, in which case the connection is
  245.  * shut down when this function returns.
  246.  */
  247. xcb_generic_event_t *xcb_poll_for_event(xcb_connection_t *c);
  248.  
  249. /**
  250.  * @brief Return the error for a request, or NULL if none can ever arrive.
  251.  * @param c: The connection to the X server.
  252.  * @param cookie: The request cookie.
  253.  * @return The error for the request, or NULL if none can ever arrive.
  254.  *
  255.  * The xcb_void_cookie_t cookie supplied to this function must have resulted
  256.  * from a call to xcb_[request_name]_checked().  This function will block
  257.  * until one of two conditions happens.  If an error is received, it will be
  258.  * returned.  If a reply to a subsequent request has already arrived, no error
  259.  * can arrive for this request, so this function will return NULL.
  260.  *
  261.  * Note that this function will perform a sync if needed to ensure that the
  262.  * sequence number will advance beyond that provided in cookie; this is a
  263.  * convenience to avoid races in determining whether the sync is needed.
  264.  */
  265. xcb_generic_error_t *xcb_request_check(xcb_connection_t *c, xcb_void_cookie_t cookie);
  266.  
  267.  
  268. /* xcb_ext.c */
  269.  
  270. /**
  271.  * @typedef typedef struct xcb_extension_t xcb_extension_t
  272.  */
  273. typedef struct xcb_extension_t xcb_extension_t;  /**< Opaque structure used as key for xcb_get_extension_data_t. */
  274.  
  275. /**
  276.  * @brief Caches reply information from QueryExtension requests.
  277.  * @param c: The connection.
  278.  * @param ext: The extension data.
  279.  * @return A pointer to the xcb_query_extension_reply_t for the extension.
  280.  *
  281.  * This function is the primary interface to the "extension cache",
  282.  * which caches reply information from QueryExtension
  283.  * requests. Invoking this function may cause a call to
  284.  * xcb_query_extension to retrieve extension information from the
  285.  * server, and may block until extension data is received from the
  286.  * server.
  287.  *
  288.  * The result must not be freed. This storage is managed by the cache
  289.  * itself.
  290.  */
  291. const xcb_query_extension_reply_t *xcb_get_extension_data(xcb_connection_t *c, xcb_extension_t *ext);
  292.  
  293. /**
  294.  * @brief Prefetch of extension data into the extension cache
  295.  * @param c: The connection.
  296.  * @param ext: The extension data.
  297.  *
  298.  * This function allows a "prefetch" of extension data into the
  299.  * extension cache. Invoking the function may cause a call to
  300.  * xcb_query_extension, but will not block waiting for the
  301.  * reply. xcb_get_extension_data will return the prefetched data after
  302.  * possibly blocking while it is retrieved.
  303.  */
  304. void xcb_prefetch_extension_data(xcb_connection_t *c, xcb_extension_t *ext);
  305.  
  306.  
  307. /* xcb_conn.c */
  308.  
  309. /**
  310.  * @brief Access the data returned by the server.
  311.  * @param c: The connection.
  312.  * @return A pointer to an xcb_setup_t structure.
  313.  *
  314.  * Accessor for the data returned by the server when the xcb_connection_t
  315.  * was initialized. This data includes
  316.  * - the server's required format for images,
  317.  * - a list of available visuals,
  318.  * - a list of available screens,
  319.  * - the server's maximum request length (in the absence of the
  320.  * BIG-REQUESTS extension),
  321.  * - and other assorted information.
  322.  *
  323.  * See the X protocol specification for more details.
  324.  *
  325.  * The result must not be freed.
  326.  */
  327. const xcb_setup_t *xcb_get_setup(xcb_connection_t *c);
  328.  
  329. /**
  330.  * @brief Access the file descriptor of the connection.
  331.  * @param c: The connection.
  332.  * @return The file descriptor.
  333.  *
  334.  * Accessor for the file descriptor that was passed to the
  335.  * xcb_connect_to_fd call that returned @p c.
  336.  */
  337. int xcb_get_file_descriptor(xcb_connection_t *c);
  338.  
  339. /**
  340.  * @brief Test whether the connection has shut down due to a fatal error.
  341.  * @param c: The connection.
  342.  * @return 1 if the connection is in an error state; 0 otherwise.
  343.  *
  344.  * Some errors that occur in the context of an xcb_connection_t
  345.  * are unrecoverable. When such an error occurs, the
  346.  * connection is shut down and further operations on the
  347.  * xcb_connection_t have no effect.
  348.  *
  349.  * @todo Other functions should document the conditions in
  350.  * which they shut down the connection.
  351.  */
  352. int xcb_connection_has_error(xcb_connection_t *c);
  353.  
  354. /**
  355.  * @brief Connects to the X server.
  356.  * @param fd: The file descriptor.
  357.  * @param auth_info: Authentication data.
  358.  * @return A newly allocated xcb_connection_t structure.
  359.  *
  360.  * Connects to an X server, given the open socket @p fd and the
  361.  * xcb_auth_info_t @p auth_info. The file descriptor @p fd is
  362.  * bidirectionally connected to an X server. If the connection
  363.  * should be unauthenticated, @p auth_info must be @c
  364.  * NULL.
  365.  */
  366. xcb_connection_t *xcb_connect_to_fd(int fd, xcb_auth_info_t *auth_info);
  367.  
  368. /**
  369.  * @brief Closes the connection.
  370.  * @param c: The connection.
  371.  *
  372.  * Closes the file descriptor and frees all memory associated with the
  373.  * connection @c c.
  374.  */
  375. void xcb_disconnect(xcb_connection_t *c);
  376.  
  377.  
  378. /* xcb_util.c */
  379.  
  380. /**
  381.  * @brief Parses a display string name in the form documented by X(7x).
  382.  * @param name: The name of the display.
  383.  * @param host: A pointer to a malloc'd copy of the hostname.
  384.  * @param display: A pointer to the display number.
  385.  * @param screen: A pointer to the screen number.
  386.  * @return 0 on failure, non 0 otherwise.
  387.  *
  388.  * Parses the display string name @p display_name in the form
  389.  * documented by X(7x). Has no side effects on failure. If
  390.  * @p displayname is @c NULL or empty, it uses the environment
  391.  * variable DISPLAY. @p hostp is a pointer to a newly allocated string
  392.  * that contain the host name. @p displayp is set to the display
  393.  * number and @p screenp to the preferred screen number. @p screenp
  394.  * can be @c NULL. If @p displayname does not contain a screen number,
  395.  * it is set to @c 0.
  396.  */
  397. int xcb_parse_display(const char *name, char **host, int *display, int *screen);
  398.  
  399. /**
  400.  * @brief Connects to the X server.
  401.  * @param displayname: The name of the display.
  402.  * @param screenp: A pointer to a preferred screen number.
  403.  * @return A newly allocated xcb_connection_t structure.
  404.  *
  405.  * Connects to the X server specified by @p displayname. If @p
  406.  * displayname is @c NULL, uses the value of the DISPLAY environment
  407.  * variable. If a particular screen on that server is preferred, the
  408.  * int pointed to by @p screenp (if not @c NULL) will be set to that
  409.  * screen; otherwise the screen will be set to 0.
  410.  */
  411. xcb_connection_t *xcb_connect(const char *displayname, int *screenp);
  412.  
  413. /**
  414.  * @brief Connects to the X server, using an authorization information.
  415.  * @param display: The name of the display.
  416.  * @param auth: The authorization information.
  417.  * @param screen: A pointer to a preferred screen number.
  418.  * @return A newly allocated xcb_connection_t structure.
  419.  *
  420.  * Connects to the X server specified by @p displayname, using the
  421.  * authorization @p auth. If a particular screen on that server is
  422.  * preferred, the int pointed to by @p screenp (if not @c NULL) will
  423.  * be set to that screen; otherwise @p screenp will be set to 0.
  424.  */
  425. xcb_connection_t *xcb_connect_to_display_with_auth_info(const char *display, xcb_auth_info_t *auth, int *screen);
  426.  
  427.  
  428. /* xcb_xid.c */
  429.  
  430. /**
  431.  * @brief Allocates an XID for a new object.
  432.  * @param c: The connection.
  433.  * @return A newly allocated XID.
  434.  *
  435.  * Allocates an XID for a new object. Typically used just prior to
  436.  * various object creation functions, such as xcb_create_window.
  437.  */
  438. uint32_t xcb_generate_id(xcb_connection_t *c);
  439.  
  440.  
  441. /**
  442.  * @}
  443.  */
  444.  
  445. #ifdef __cplusplus
  446. }
  447. #endif
  448.  
  449.  
  450. #endif /* __XCB_H__ */
  451.